 Acrobat file (24K) |
 AppleWorks file (44K) |
On Launching an App with a Document
| Technote 1002 | OCTOBER 1995 |
This Note addresses the issue of how to launch another application from inside your app and then open a document using that app. Preferably, developers would like to utilize the signature information from the document to find the application.
Developers writing applications that sub-launch other applications will find the material contained herein lets them easily extend the functionality of their applications to include the ability to launch applications with the specific documents they want to be opened.
This Note combines information found in the chapter "Creating and Sending Apple Events" in Inside Macintosh: Interapplication Communications
and the chapter "Desktop Manager" in Inside Macintosh: More Macintosh Toolbox. The format of the Open Documents event is described in the
section "Handling the Required Apple Events" (4-11) in Inside Macintosh: Interapplication Communication.
Contents
About Launching an Application with a Document
To launch an application with a document, the following steps are required:- 1. Find the appropriate application for opening the document
- 2. Try sending the open documents event to the running application, and
- 3. If Step 2 fails, launch the application with the appropriate parameters.
Finding the Right Application for the Document
Every document has type and creator bytes associated with it. The first step, therefore, in finding what application to use is to take a look at the creator bytes. You can find this value by using the FSpGetFInfo call:err = FSpGetFInfo(&spec, &fndrInfo);fndrInfo.fdCreator contains the creator bytes for the document.
When specifying the destination address for the open document Apple event, the creator bytes are used to create a descriptor containing a typeApplSignature record. If the AESend indicates that no such application with that creator is running, then the creator bytes can be used to search the desktop files on attached volumes for the correct application to launch.
Using a Preferred Application to Open the Document
Sometimes, you may want to open a document using an application other than the one referred to by its creator bytes. For example, you may want to open every text document you encounter using a program such as AppleWorks. In that case, you need to provide some internal means of mapping file types to creator types inside of your application that overrides the creator bytes returned byFSpGetFInfo. The code snippet in this Technote provides a means for doing this by allowing you to define a mapping function for re-mapping the creator type used to open a document.
Here is how you would define a simple mapping function that will work with LaunchTheDocument:
void MyMapCreator(FSSpec *document, OSType type, OSType *creator) {Mapping functions receive three parameters: a FSSpec record referring to the document itself -- in case you want to look at the document's data or name to establish its type -- and the document's type and creator bytes. Mapping functions provide a simple way for your application to change the creator bytes that will be used to find the appropriate application before the search for the application begins. In this example, all documents of type 'TEXT' are re-mapped to the creator bytes for AppleWorks, telling
if (type == 'TEXT')
*creator = 'BOBO'; /* open all text files with AppleWorks,
creator = 'BOBO' */
}
LaunchTheDocument to ask AppleWorks to open all text documents. The collected fragments in a code snippet provided later in this Technote give you an example of how to define a creator mapping function.Sending the Open Documents Event
As described in Inside Macintosh: Interapplication Communication (4-13), the open documents event contains one list of alias records referring to documents to be opened by the target application. The following description takes you through the step-by-step construction of such an event.
First, create an address descriptor record (target_desc), using the creator bytes (fndrInfo.fdCreator):
err = AECreateDesc(typeApplSignature, (Ptr) &fndrInfo.fdCreator,Then you use this address record to specify the target application when you create the Apple event (the_apple_event):
sizeof(OSType), &target_desc);
err = AECreateAppleEvent(kCoreEventClass, kAEOpenDocuments,Because you are opening a single document, you need to create a list containing an alias record referring to the file you want to open. Even though you're only asking the target application to open one document, you still create a list containing only one alias record to conform to the definition of an open documents Apple event.
&target_desc, kAutoGenerateReturnID, kAnyTransactionID,
&the_apple_event);
First, you create a list (files_list):
err = AECreateList(NULL, 0, false, &files_list);and a descriptor record (file_desc) containing an alias to our document (the_file):
err = NewAlias(NULL, &the_file, &the_alias);Then, you add the descriptor record (
HLock((Handle) the_alias);
err = AECreateDesc(typeAlias, (Ptr) (*the_alias),
GetHandleSize((Handle) the_alias), &file_desc);
HUnlock((Handle) the_alias);
file_desc) containing the alias to the list (files_list):err = AEPutDesc(&files_list, 0, &file_desc);Now that you have the Apple event (the_apple_event), and the list (files_list), containing an alias record referring to the file you want opened, you can take the list and put it into the Apple event (the_apple_event) as an Apple event parameter:
err = AEPutParamDesc(&the_apple_event, keyDirectObject, &files_list);At this point the open documents event (the_apple_event) has been set up correctly and you can send it to the application:
err = AESend(&the_apple_event, &the_reply, kAENoReply,
kAENormalPriority, kNoTimeOut, NULL, NULL);
When the application is not running
WhenAESend returns an error result of connectionInvalid, this means the application with the specified creator bytes is not currently registered with the Process Manager. In this case, the correct application must be launched before it can be sent the open document event. The first thing to do here is search through the desktop files on connected volumes using the PBDTGetAPPL routine to find the application with the correct creator bytes for the document. The following code fragment illustrates how this can be done.
HVolumeParam vol_pb;
DTPBRec desktop_pb;
FSSpec application;
vol_pb.ioNamePtr = NULL;
err = fnfErr; /* default return value */
vol_pb.ioNamePtr = NULL;
/* for... every connected volume, 1, 2, ... */
for (vol_pb.ioVolIndex = 1;
PBHGetVInfoSync((HParmBlkPtr) &vol_pb) == noErr;
vol_pb.ioVolIndex++) {
/* PBHGetVolParms call to ensure the volume is a local volume */
param_pb.ioVRefNum = vol_pb.ioVRefNum;
if (PBHGetVolParmsSync((HParmBlkPtr)¶m_pb) == noErr
&& volinfo.vMServerAdr == 0) {
/* call PBDTGetPath to find the desktop file on the volume */
desktop_pb.ioCompletion = NULL;
desktop_pb.ioVRefNum = vol_pb.ioVRefNum;
desktop_pb.ioNamePtr = NULL;
desktop_pb.ioIndex = 0;
if (PBDTGetPath(&desktop_pb) == noErr) {
desktop_pb.ioFileCreator = app_creator_bytes;
desktop_pb.ioNamePtr = application.name;
if (PBDTGetAPPLSync(&desktop_pb) == noErr) {
application.vRefNum = vol_pb.ioVRefNum;
application.parID = desktop_pb.ioAPPLParID;
/* at this point we have found the correct application */
err = noErr;
break;
}
}
}
}
- Note:
- This is a fairly simple search method. For your purposes, you may want to modify it so it does special things, such as not
bothering with ejected disks that are still mounted, or searching particular disks before others. The code fragment searches local volumes only checking
to see if they are local using the
PBHGetVolParmsroutine. In the code snippet in this Technote, local volumes are searched before an optional search of non-local volumes takes place.
Launching the App
Once you find the correct application, the next step is to coerce the Apple event thatAESend failed to send into the correct format so a pointer to the parameters can be stored in the launch parameter block. This can be achieved with a call to AECoerceDesc specifying typeAppParameters as the destination type:err = AECoerceDesc(&the_apple_event, typeAppParameters, ¶meter_desc);Once this coercion has been performed, everything required for setting up the launch parameter block is available so the application can be launched:
launch_pb.launchBlockID = extendedBlock;
launch_pb.launchEPBLength = extendedBlockLen;
launch_pb.launchFileFlags = 0;
launch_pb.launchControlFlags =
launchContinue + launchNoFileFlags;
launch_pb.launchAppSpec = &application;
/* launchAppParameters expects a pointer,
so we lock and dereference the dataHandle
stored in the parameter_desc */
HLock((Handle) parameter_desc.dataHandle);
launch_pb.launchAppParameters =
(AppParametersPtr) (*parameter_desc.dataHandle);
err = LaunchApplication(&launch_pb);
HUnlock((Handle) parameter_desc.dataHandle);
If the Target Application is Not Apple Event Aware
If the target application is not high level event aware (pre-System 7), the Apple Event Manager will automatically coerce the event into the old style launch parameters when the program is being launched. The old style 'mstr' and 'mst#' resources used by MultiFinder in System 6 are no longer supported; therefore, you can't use these routines to open the document if the application is already running.Collected Fragments in a Code Snippet
The following code snippet combines all of the concepts previously explained.- Note:
- The author has compiled and run the following with the MPW C, MPW PPC, SymantecC, MrC, and CodeWarrior C compilers and is satisfied that it is bug free for System 7.0 and onward.
/* File SendOpen.c
Code snippet illustrating how to launch an application and send it
an open document Apple event.
by John Montbriand, 1995.
Copyright (C) 1995 by Apple Computer, Inc. All Rights Reserved.*/
#include <Types.h>
#include <QuickDraw.h>
#include <Fonts.h>
#include <Windows.h>
#include <TextEdit.h>
#include <Dialogs.h>
#include <Menus.h>
#include <AppleEvents.h>
#include <StandardFile.h>
#include <Files.h>
#include <Errors.h>
#include <Aliases.h>
/* MapCreatorProcs, when provided as a parameter to LaunchTheDocument,
will be called to allow your app to re-map the creator type for a file
to a different creator type. Your function should either modify *creator
to refer to a preferred application by replacing its value with the
value of the preferred application's creator bytes, or leave *creator
untouched if you want the creator bytes from the document to be used. */
typedef void (*MapCreatorProc)(FSSpec *document, OSType type, OSType
*creator);
/* LaunchTheDocument attempts to open the document with either an application that is already loaded in memory and running, or by finding and launching the appropriate application with the document as a parameter. If no application can be found with the creator bytes found in the document, fnfErr is returned. Local Volumes are searched before remote server volumes. Remote server volumes are only searched if use_remote_apps is true. If the optional creator remapping procedure is provided (remap != NULL), then it will be called to allow the caller to re-map the creator bytes to a preferred application for the document's type.. */